Aminet 52

home *** CD-ROM | disk | FTP | other *** search

/ Aminet 52 / Aminet 52 (2002)(GTI - Schatztruhe)[!][Dec 2002].iso / Aminet / misc / emu / Apex-src.lha / TUTORIAL.DOC < prev next >

Wrap

Text File | 2001-10-01 | 24.4 KB | 809 lines

APEX ON THE AMIGA A TUTORIAL OVERVIEW SEP-22-87 CONTENTS INTRODUCTION . . . . . . . . . . . 1 BOOTUP . . . . . . . . . . . . . 1 THE DIRECTORY . . . . . . . . . . . 2 THE TITLE . . . . . . . . . . . . 2 THE DATE . . . . . . . . . . . . 2 RUNNING PROGRAMS UNDER APEX . . . . . . 3 THE TEXT EDITOR . . . . . . . . . . 3 MOVING THE CURSOR . . . . . . . . . 4 COMMAND-LINE COMMANDS . . . . . . . . 4 EXITING FROM THE EDITOR . . . . . . . 6 DEFAULT FILES . . . . . . . . . . . 6 AN XPL0 PROGRAM . . . . . . . . . . 7 COMPILING AND EXECUTING AN XPL0 PROGRAM . . 7 RUNNING AN ASSEMBLY LANGUAGE PROGRAM . . . 8 A MORE ELABORATE XPL0 PROGRAM . . . . . 10 TYPES OF APEX FILES . . . . . . . . . 11 INSTALLING A PRINTER HANDLER . . . . . . 12 BACKUP FILES . . . . . . . . . . . 13 SQUASH . . . . . . . . . . . . . 13 DELETE . . . . . . . . . . . . . 14 COPY . . . . . . . . . . . . . . 14 HELP . . . . . . . . . . . . . . 14 INTRODUCTION Apex is designed to help programmers create and test programs. This tutorial describes how to use it to write programs in both XPL0 and assembly language. But Apex is not just limited to programming, it is useful for creating any kind of text -- like this tutorial for example. Apex is a disk operating system. It is an alternative to Amiga DOS. An operating system is the highest level program in your computer. It is used to run other programs and to manage various kinds of files. This tutorial is intended to get you started. It presents enough infor- mation about a few commands so that you can experiment with the re- maining commands as you learn them. It makes no attempt to fully explain all the intricacies of the commands presented, nor to cover all of the commands in Apex. To run version 1.8 Apex, you must have an Amiga A1000 with 512K of RAM. Currently, it will not run on the A500 or A2000. Also, it is assumed that you have either an Epson or C.Itoh printer (or compatible) con- nected to the parallel port. BOOTUP The Apex System disk boots in place of the Amiga Kickstart disk. Insert the Apex System disk into the internal drive and boot it in the normal manner -- by either turning on power, or by simultaneously pressing both Amiga (A) keys and the <CTRL> key. You should see something like this: A P E X / \ / \ BY COMPUTER APPLICATIONS 4334 EAST 17TH AVENUE DENVER COLORADO 80220 TYPE "HELP" FOR INSTRUCTIONS -- APEX V1.8x17 -- DATE FROM SYSTEM UNIT: TUE, SEP-15-87 RELOADED FROM UNIT 0 APX> THE DIRECTORY After the Apex prompt, type: APX>DIR 0<RETURN> The <RETURN> notation means press the RETURN key. Also, "APX>" is shown for orientation. It should not be typed in. You should see the directory of the disk, which shows the current date, the volume number, the unit number, the title, and a list of all the files on the disk. If the directory is longer than one screen, then press any key to see the rest of it. To see the long form of the directory, type: APX>DIR 0/L<RETURN> This shows additional information about the files. It shows the length of the files in blocks, their creation date, and their location on the disk. Apex divides units into blocks. Each block contains 256 bytes, or char- acters, of information. The 3-1/2 inch Amiga disk can hold 3520 blocks. There is also a backup directory, which can be used in the event the main directory is damaged. To display the backup directory, enter the command: APX>BDIR 0<RETURN> THE TITLE You can change the title of your disk by using the TITLE command. For example, type: APX>TITLE 1:WORK SPACE<RETURN> Now use the directory command to verify that the title has changed: APX>DIR 1<RETURN> Using the correct title will help you organize your work. THE DATE Set the current date by typing: APX>DATE<RETURN> Apex replies: NEW DATE (MM-DD-YY)? Enter the date in the form month-day-year, for example: 9-20-87. Apex echoes this new date, and to verify it, displays the day of the week. The current date is used as the creation date of any files that you make. It is very helpful for determining the latest version of a file. You should set the date whenever you bootup for the first time each day. RUNNING PROGRAMS UNDER APEX To run a program under Apex, you simply type its name (you don't type "RUN"). This makes running a program look the same as executing an Apex command. In fact some programs are so closly associated with Apex that it is difficult to tell that they are not commands. These programs are considered part of the Apex system and are called utilities. DIR, TITLE, and DATE are commands, but as we will see in a moment, ED is a utility. THE TEXT EDITOR The text editor is a program that enables you to easily write and modify any kind of text. When programs become large or lines become intricate, it is important to be able to locate, modify, and insert code. The editor allows you to do this. It permits you, for example, to search for misspelled words, delete them, and insert the corrections. Before you can use the editor, you need to create a file using the MAKE command. Type: APX>MAKE 1:AFILE.TXT<RETURN> Now start the editor by typing: APX>ED 1:AFILE.TXT<RETURN> You should see a display that looks like this: # #---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+ -- ED, Version 1.0x15 -- For help type <ESC>?<ESC><ESC> eof CMD: 0 SCOOP: 5000 S # s --> REM: 80000 AT: 0 COL:0 To enter text, you just start typing. Type: This is my first line using ED.<RETURN> This is my second line.<RETURN> MOVING THE CURSOR The ED editor has a number of commands that are performed by typing control characters. Control characters are typed by using the <CTRL> key like the <SHIFT> key, that is, by holding the <CTRL> key down while typing the character. After you have typed the lines above, the cursor will be at the end. Move it to the beginning by typing CTRL-E. Now change the word "first" to "changed" by moving the cursor forward by repeatedly typing CTRL-A until it is at the end of the word "first". Now use the back-arrow key to delete "first". Finally, type the word "changed". The commands you need most often are the ones that move the cursor. They are: CTRL-A Move ahead one character CTRL-S Move ahead one line CTRL-D Move to the end of text CTRL-Q Move back one character. CTRL-W Move back one line CTRL-E Move to the beginning of text These particular keys were chosen for their location on the keyboard rather than for their mnemonic value. Notice that the keys to move ahead are on the home row and that the keys to move backward are immediately above them in corresponding order. Practice moving the cursor right now, just to get the feel of these keys. COMMAND-LINE COMMANDS Now press the <ESC> key and you should see another cursor appear one line from the bottom of the screen. This line is called the command line, and it provides a second set of commands. Perhaps the most useful command for a beginner is the help command. Type "?<ESC><ESC>", and you will see a summary of all the commands. (Press <RETURN> two times to get back to the normal text display.) Another way to position the cursor is by using the search command. First type a CTRL-E to move the cursor to the beginning of the text, then type: <ESC>ssecond<ESC><ESC> Your typing should appear on the command line. The "s" indicates a search command. The word "second" is the word being searched for. The first <ESC> ends the search, and the second <ESC> executes the command. The search command can be typed as either "s" or "S", but the case of the word being searched for should match the case of the word in the text. The search command is not limited to searching for single words. Several words, or just about any group of characters, called a string, can be used. When a search succeeds, the flashing cursor will move to the end of the matching string. Occasionally, nothing appears to happen because the search fails. When this occurs, "none?" will be displayed in the lower left-hand corner. This means that the string being searched for doesn't exist in the text being searched. Either the cursor was beyond the matching string, or perhaps because of a typo, the string in the command didn't match the one in the text. You can also delete characters from the command line. For example, type: <ESC>6d<ESC><ESC> The six characters preceeding the cursor, the word "second", is deleted. Now type: <ESC>ithird<ESC><ESC> The word "third" is inserted into the text. The command line can be used to combine commands. For example, press <ESC> to start the command line, then type: <CTRL-E>sthird<ESC>5d<ESC>ifourth<ESC><ESC> This series of commands moves the cursor to the beginning of the text, searches for the word "third", and replaces it with "fourth". You have now learned two methods for searching, deleting, and inserting characters. The first method used the immediate commands, where control characters and the back arrow were used. The second method made use of the command line, using the S, D, and I commands. As your experience with the editor increases, you will learn to chose between these two methods. The immediate commands are useful for quick and simple changes, while the command line can be used to combine commands to perform elaborate editing tasks. EXITING FROM THE EDITOR To exit from the editor type: <ESC>Q<ESC><ESC> This is the normal method of exiting. It automatically saves your text in the output file and returns you to Apex. However, if you don't want to save your text, then use the command: <ESC>T<ESC><ESC> DEFAULT FILES Apex has a system of defaults that can be used to significantly reduce typing. As you write programs, you will be editing, compiling, and running the same program many times. Using the defaults allows you to perform these operations without typing the unit number and file name every time you refer to them. Set the default unit and file name for the program described below by typing: APX>DFILE 1:HELLO.XPL<RETURN> Apex replies: DEFAULT NAME: 1:HELLO .XPL BACKUP: T ABORT: T PACK: F CHECK: F Another way Apex saves typing is by allowing you to abbreviate all commands to just the first two letters. Now type: APX>MA<SPACE><RETURN> The command MAKE is abbreviated to MA, and the <SPACE> tells Apex that the command is going to use the default file. Apex says: CLOSING: 1:HELLO .XPL 1 TODAY 443-443 If you forget the <SPACE>, Apex says: NOPE - NEED FILE NAME. Apex doesn't know the name of the file because it needs the <SPACE> to tell it to use the default file name. AN XPL0 PROGRAM After you have made the default file above, you are ready to use the editor to write a program using the XPL0 language. Type: APX>ED<SPACE><RETURN> Remember the <SPACE>. If you forget it here, Apex will start the editor with no output file opened, and it will be slightly difficult to save your text. Once you are in the editor, type in the following program: code TEXT=12; begin TEXT(0,"HELLO WORLD! "); end; The lowercase words have special meaning to XPL0. The word "code" is used to declare built-in routines called intrinsics. Intrinsic 12 outputs a text string. The name used here, TEXT, is the conventional one for this intrinsic. Notice that a carriage return is inserted in the text string by simply placing it within the quotes. The words "begin" and "end" signify the beginning and ending of a block of statements. In this case there is only a single statement. The zero in TEXT(0,...) specifies that the string is to go to Apex device 0, the video screen. Semicolons (;) are used at the end of declarations and to separate statements. Save this text and return to Apex by typing: <ESC>Q<ESC><ESC> COMPILING AND EXECUTING AN XPL0 PROGRAM XPL0 is a compiled language. Compiling is the process of translating a program into a form that is more easily understood by the computer. BASIC interprets a program step-by-step every time it runs; whereas XPL0 translates a program in a separate step that precedes the actual execution. This compilation step is the major reason an XPL0 program typically runs a hundred times faster than a similar BASIC program. To compile your program, type: APX>XPL<SPACE><RETURN> This starts the XPL0 compiler. Remember, the <SPACE> tells Apex to use the default file, HELLO.XPL. ("XPL" cannot be abbreviated to "XP" because it is the name of a program, not an Apex command.) XPL0 replies: -- XPL0 COMPILER, VER 5.7-68Kx15 -- CHANGE DEFAULTS (N/Y)? The defaults specify the input and output device numbers. For our example they are fine, so simply type <RETURN> ("No" is assumed). If you made any typos, the compiler will stop, give an error message, and ask if it should continue. Note the cause of the error and type <RETURN> to continue ("Yes" is assumed). You might need to hit <RETURN> several times because some errors get the compiler out of sync with the code. Edit the file to correct any errors and try again. Once your program has successfully compiled, execute it by typing: APX>LOAD<SPACE><RETURN> Again the defaults are fine, so simply type <RETURN> to start loading. This loads the compiled version of your program, HELLO.OBJ. After the program is loaded, you will see: PRESS "RETURN" TO EXECUTE (OR CTRL-P TO SAVE) Press <RETURN> and you should see: HELLO WORLD! You have written, compiled, and run an XPL0 program. CONGRATULATIONS! RUNNING AN ASSEMBLY LANGUAGE PROGRAM If you would like to write the HELLO program in assembly language, set the default file name, make the file, and start the editor as follows: APX>DF 1:HELLO.68K<RETURN> APX>MA<SPACE><RETURN> APX>ED<SPACE><RETURN> Enter the following text using the editor. The separators between the columns of the program are TABs, not spaces. Be sure to put a <RETURN> at the end of the END line. ;HELLO.68K SEP-20-87 ;This program displays "HELLO WORLD!" on the video monitor. CR EQU $0D ;ASCII carriage return code DEVICE EQU $517 ;Address of DEVICE number variable VRENTR EQU $7B4 ;Vector to Apex re-entry point VDEVHAN EQU $7E4 ;Routine to handle device I/O ORG $400 ;System page location for start vector JMP START.L ; (The LOADer jumps to $400) ORG $3000 ;Start of free space for user programs START MOVE.B #0,DEVICE ;Output to device 0, the video display MOVEA.W #12,A6 ;Set I/O function code to OUTPUT MOVEA.L #HELLO,A0 ;Point A0 to our text string BRA.S HEL20 ;Enter loop HEL10 JSR VDEVHAN ;Output byte in D0 to selected device HEL20 MOVE.B (A0)+,D0 ;Get char from string, bump pointer BNE.S HEL10 ;Loop back if not zero byte JMP VRENTR ;Re-enter Apex HELLO ASCII "HELLO WORLD!" ;Text string DC.B CR ;Carriage return (new line) DC.B 0 ;String terminator END ;End of program To assemble this program type: APX>ASM<SPACE><RETURN> The assembler begins by displaying: -- ASM68K, V1.0x10 -- CHANGE DEFAULTS (N/Y)? The defaults are fine, so simply type <RETURN> to start assembling ("No" is assumed). The assembler indicates any errors it finds and the total number of errors detected. Correct any errors using the editor and try again. When the program assembles without error, load it by typing: APX>LOAD<SPACE><RETURN> Again the defaults are fine, so simply type <RETURN> to start loading. To execute the program, type <RETURN> a second time. You should see: HELLO WORLD! A MORE ELABORATE XPL0 PROGRAM A program that displays "HELLO WORLD!" is of marginal utility, but with only slightly more effort you can create a program that lists any Apex text file on the video screen. Start this new program by typing: APX>DF 1:PRINT.XPL<RETURN> Make the file in the same manner as you did for the program HELLO.XPL then enter the editor and type in the following: \PRINT.XPL SEP-20-87 \THIS PROGRAM PRINTS TEXT FILES. code CHIN=7, CHOUT=8, OPENI=13, OPENO=14, CLOSE=15; integer CH; define IN=3, OUT=0; define EOF=$1A; \CTRL-Z begin OPENI(IN); OPENO(OUT); CH:= CHIN(IN); while CH#EOF do begin CHOUT(OUT,CH); CH:= CHIN(IN); end; CLOSE(OUT); end; This program has a number of new XPL0 features. First is the "\". The backslash is the XPL0 designator for a comment. The intrinsic CHIN (code 7) gets a character from an input device. The opposite of CHIN is CHOUT, which outputs a character to an output device. The intrinsics OPENI and OPENO open (initialize) devices for input and output respectively, while the intrinsic CLOSE closes an output device. Devices don't always need to be opened and closed, but until you become more familiar with XPL0, it's a good idea to use these intrinsics. The variable CH is declared as an integer in the forth line. Unlike BASIC or FORTRAN, XPL0 requires that variables, as well as all named things, be declared before they are used. Next are the define declarations. These are used to give names to constants. A defined constant can be used just like a variable, except that its value cannot be changed as the program executes. The constant EOF is set to a hexadecimal value of 1A. The value $1A is equivalent to a CTRL-Z, which is used by Apex as an end-of-file mark. The symbol "#" is used to represent "not equal". The main body of the program reads, translated into English: While X is not equal to the end- of-file mark, output the character to device 0, the video screen, and input another character from device 3, a disk file. After you have entered and compiled this program, make it a .SAV file so that it will be easy to run. Load the program using LOAD, then when the message: PRESS "RETURN" TO EXECUTE (OR CTRL-P TO SAVE) appears, type a CTRL-P. When the Apex prompt appears, type: APX>SAVE<SPACE><RETURN> This creates a .SAV file, which is a copy of the executable form of your program. Run this program by typing its unit number and name followed by the name of the file you want to print. For example, this prints the program that you just created: APX>1:PRINT PRINT.XPL<RETURN> TYPES OF APEX FILES List the directory and notice the files PRINT.XPL, PRINT.OBJ, and PRINT.SAV. PRINT.XPL is the source file that you created using the editor. PRINT.OBJ is the XPL0 compiler output file. Type: APX>1:PRINT PRINT.OBJ<RETURN> You should see something like this: ;000048E77F80204D4BED000472032A814EB8084E42954EB8085472032A814EB8 082A20802210741AB2826700FFD67200241048D500064EB8083072032A814EB8 082A208060DE^002A42954EB8085A2A484CDF01FE4E75 This listing is in hexadecimal ASCII and is decipherable with effort, but is certainly less understandable by humans than the original source. The two files, PRINT.XPL and PRINT.OBJ, consist entirely of ASCII characters that can be displayed on the video screen. Listing the PRINT.SAV file gives a bizarre combination of characters and graphics. This file is a binary memory image of your executable program, and it is not meant to be listed. INSTALLING A PRINTER HANDLER You might want to modify your PRINT.XPL program so that it will output to the printer instead of the video screen. All you have to do is change the fifth line from OUT=0 to OUT=2. However, this program already exists. It's the utility called PR. Now use PR (or your modified PRINT program) to test your printer by typing: APX>PR PRINT.XPL<RETURN> Your program, PRINT.XPL, should be listed on the printer. If it didn't list or if you got a bunch of garbage, then you need to install a different printer handler. Even if you do get a correct listing, you might want to install either the Epson or C.Itoh handler. These handlers use elite characters and print 96 columns instead of the standard handlers, which use pica characters and only print 80 columns. A printer handler is a routine that handles the details of communi- cating between Apex and a printer. It relieves the programmer from worrying about what type of printer is actually being used, and it provides a uniform way of handling characters and commands. It also provides additional intelligence, which for example, is used to put margins at the top and bottom of each page. There are many manufacturers of printers. Luckily, they tend to standardize on just a few different types. Epson-type printers include Epson, Comrex, and Star Gemini. C.Itoh-type printers include C.Itoh, Prowriter, and NEC. PRINTER HANDLER Epson EPSONHAN.OBJ 96 columns (elite) C.Itoh ITOHAN.OBJ 96 columns (elite) others PARHAN.OBJ 80 columns (pica) DUMHAN.OBJ 80 columns, no intelligence To install, for example, the C.Itoh handler, type: APX>INSTALL 0:ITOHAN<RETURN> Answer the questions as follows: WHICH UNIT: 0<RETURN> LOADING... MODIFYING 0:RESCOD.SYS - ARE YOU SURE (N/Y)? Y<RETURN> The new handler is now installed on your Apex System disk, but it is not loaded into memory ready for use. To load the new handler, you must re- boot. Test this handler by rebooting and printing PRINT.XPL as you did above. BACKUP FILES Apex automatically saves backup copies of your files. This allows you to recover the previous version of a file. Type: APX>LIST PRINT.BAK<RETURN> You should see the previous version of your program, PRINT.XPL. If you attempt to edit this backup file by typing: APX>ED PRINT.BAK<RETURN> you will get an error message because Apex will not allow you create an output file with the extension ".BAK". You can explicitly indicate an output file with a valid extension by doing this: APX>ED PRINT.XPL<PRINT.BAK<RETURN> Although it's a good idea to have Apex save backup copies of your files, you might not always want it to. For example, if your disk is getting too full. You can turn off backups with the command: APX>NO BACKUP<RETURN> To turn backups on again, type: APX>DO BACKUP<RETURN> To see the current state of the backup option, use the DFILE command. SQUASH Apex writes files in contiguous sectors. This makes disk accesses faster than they are with Amiga DOS, which uses linked sectors. However, with Apex, as you use the disk, the free space tends to become chopped up into little pieces. This free space might become so fragmented that a file will not fit even though there is plenty of free space on the disk. Now type: APX>DI 1<RETURN> Notice the last line. FREE tells you the total number of unused blocks on the unit. MAX tells you the largest file you can save on the unit. Observe that MAX is less than FREE. The squash command, SQ, moves all the files to the beginning of the disk leaving all the free space at the end. Type: APX>SQ 1<RETURN> Now look at the directory and notice that FREE and MAX are the same. DELETE To remove files from the directory, use the DELETE command. For example: APX>DE AFILE.TXT<RETURN> Apex replies: REMOVING 1:AFILE .TXT 1 TODAY 443-443 - ARE YOU SURE (N/Y)? Type: Y<RETURN> to actually delete this file. In Apex an asterisk (*) is used as a wild-card substitution. For example: APX>DE *.BAK<RETURN> deletes all of the files with the extension ".BAK". COPY Whereas DUP was used to duplicate an entire disk, COPY is used to copy individual files. For example, copy the file XPLCODES.XPL from unit 0 to unit 1 as follows: APX>COPY<RETURN> FILE? XPLCODES.XPL<RETURN> FROM, TO UNITS? 0,1<RETURN> After the file is copied, COPY will prompt you for another file name. When you want to return to Apex, just press <RETURN> without a file name. HELP The HELP utility provides a summary of all the Apex commands and of some of the more common utilities. If you have not yet tried it, type: APX>HELP<RETURN> Good luck! ex commands and of s